<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html><head><title>Programming in Lua : 23.1</title>
<link rel="stylesheet" type="text/css" href="pil.css">
</head>
<body>
<p class="warning">
<A HREF="contents.html"><IMG TITLE="Programming in Lua (first edition)" SRC="capa.jpg" ALT="" ALIGN="left"></A>This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.<BR>The third edition targets Lua 5.2 and is available at <A HREF="http://www.amazon.com/exec/obidos/ASIN/859037985X/theprogrammil3-20">Amazon</A> and other bookstores.<BR>By buying the book, you also help to <A HREF="../donations.html">support the Lua project</A>.
</p>
<table width="100%" class="nav">
<tr>
<td width="10%" align="left"><a href="23.html"><img border="0" src="left.png" alt="Previous"></a></td>
<td width="80%" align="center"><a href="contents.html"><font face="Helvetica,Arial,sanserif">
<font color="gray">Programming in </font><font color="blue"> Lua</font>
</font></a></td>
<td width="10%" align="right"><a href="23.1.1.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
<tr>
<td width="10%" align="left"></td>
<td width="80%" align="center"><a href="contents.html#P3">Part III. The Standard Libraries</a>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<a href="contents.html#23">Chapter 23. The Debug Library</a></td>
<td width="10%" align="right"></td></tr>
</table>
<hr/>
<p><h2>23.1 &ndash; Introspective Facilities</h2>

<p>

<p>The main introspective function in the debug library
is the <code>debug.getinfo</code> function.
Its first parameter may be a function or a stack level.
When you call <code>debug.getinfo(foo)</code> for some function <code>foo</code>,
you get a table with some data about that function.
The table may have the following fields:
<ul>

<p><li><code>source</code> --- Where the function was defined.
If the function was defined in a string (through <code>loadstring</code>),
<code>source</code> is that string.
If the function was defined in a file,
<code>source</code> is the file name prefixed with a `<code>@</code>&acute;.

<p><li><code>short_src</code> --- A short version of <code>source</code> (up to 60 characters),
useful for error messages.

<p><li><code>linedefined</code> --- The line of the source where the function was defined.

<p><li><code>what</code> --- What this function is.
Options are <code>"Lua"</code> if <code>foo</code> is a regular Lua function,
<code>"C"</code> if it is a C function,
or <code>"main"</code> if it is the main part of a Lua chunk.

<p><li><code>name</code> --- A reasonable name for the function.

<p><li><code>namewhat</code> --- What the previous field means.
This field may be <code>"global"</code>, <code>"local"</code>, <code>"method"</code>,
<code>"field"</code>, or <code>""</code> (the empty string).
The empty string means that Lua did not find a name for the function.

<p><li><code>nups</code> --- Number of upvalues of that function.

<p><li><code>func</code> --- The function itself; see later.

<p></ul>

<p>When <code>foo</code> is a C function,
Lua does not have much data about it.
For such functions, only the fields
<code>what</code>, <code>name</code>, and <code>namewhat</code> are relevant.

<p>When you call <code>debug.getinfo(n)</code> for some number <em>n</em>,
you get data about the function active at that stack level.
For instance, if <em>n</em> is 1, you get data about the
function doing the call.
(When <em>n</em> is 0, you get data about <code>getinfo</code> itself,
a C function.)
If <em>n</em> is larger than the number of active functions in the stack,
<code>debug.getinfo</code> returns <B>nil</B>.
When you query an active function,
calling <code>debug.getinfo</code> with a number,
the result table has an extra field,
<code>currentline</code>,
with the line where the function is at that moment.
Moreover, <code>func</code> has the function that is active at
that level.

<p>The field <code>name</code> is tricky.
Remember that,
because functions are first-class values in Lua,
a function may not have a name, or may have several names.
Lua tries to find a name for a function by looking for a global
variable with that value,
or else looking into the code that called the function,
to see how it was called.
This second option works only when we call
<code>getinfo</code> with a number,
that is, we get information about a particular invocation.

<p>The <code>getinfo</code> function is not efficient.
Lua keeps debug information in a form that
does not impair program execution;
efficient retrieval is a secondary goal here.
To achieve better performance,
<code>getinfo</code> has an optional second parameter that
selects what information to get.
With this parameter,
it does not waste time collecting data that the
user does not need.
The format of this parameter is a string,
where each letter selects a group of data,
according to the following table:
<p><table align="center" border=1>
<tr><td>`<code>n</code>&acute;</td><td>selects fields <code>name</code> and <code>namewhat</code></td></tr>
<tr><td>`<code>f</code>&acute;</td><td>selects field <code>func</code></td></tr>
<tr><td>`<code>S</code>&acute;</td><td>selects fields <code>source</code>, <code>short_src</code>, <code>what</code>,
  and <code>linedefined</code></td></tr>
<tr><td>`<code>l</code>&acute;</td><td>selects field <code>currentline</code></td></tr>
<tr><td>`<code>u</code>&acute;</td><td>selects field <code>nup</code></td></tr>
</table><p>

<p>
The following function illustrates the use of <code>debug.getinfo</code>.
It prints a primitive traceback of the active stack:
<pre>
    function traceback ()
      local level = 1
      while true do
        local info = debug.getinfo(level, "Sl")
        if not info then break end
        if info.what == "C" then   -- is a C function?
          print(level, "C function")
        else   -- a Lua function
          print(string.format("[%s]:%d",
                              info.short_src, info.currentline))
        end
        level = level + 1
      end
    end
</pre>
It is not difficult to improve this function,
including more data from <code>getinfo</code>.
Actually, the debug library offers such an improved version,
<code>debug.traceback</code>.
Unlike our version, <code>debug.traceback</code> does not print its result;
instead, it returns a string.

<hr/>
<table width="100%" class="nav">
<tr valign="top">
<td width="90%" align="left">
<small>
  Copyright &copy; 2003&ndash;2004 Roberto Ierusalimschy.  All rights reserved.
</small>
</td>
<td width="10%" align="right"><a href="23.1.1.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
</table>


</body></html>

